Skip to content

Conversation

@kaleko
Copy link
Contributor

@kaleko kaleko commented Oct 16, 2025

Amazon Bedrock AgentCore Samples Pull Request

Important

  1. We strictly follow a issue-first approach, please first open an issue relating to this Pull Request.
  2. Once this Pull Request is ready for review please attach review ready label to it. Only PRs with review ready will be reviewed.

Issue number:

Concise description of the PR

Added AWS CDK implementation for the basic-runtime sample as an alternative to CloudFormation. Features clean stack definition, S3 assets for source packaging, and automated CodeBuild integration for Docker image building without local Docker dependencies. I plan to create CDK implementations for the other samples once this is approved.

User experience

Before this change:

  • Users only had CloudFormation (YAML) option for deploying basic-runtime sample
  • Source code embedded in YAML templates

After this change:

  • Users can choose between CloudFormation or CDK based on preference
  • CDK provides programmatic approach with Python
  • Cleaner code organization with separated constructs (AgentCoreRole, build trigger Lambda)
  • Source code read from disk and packaged as S3 assets
  • Consistent deployment experience with cdk deploy
  • Updated documentation reflects both CloudFormation and CDK options

Checklist

If your change doesn't seem to apply, please leave them unchecked.

  • I have reviewed the contributing guidelines
  • Add your name to CONTRIBUTORS.md
  • Have you checked to ensure there aren't other open Pull Requests for the same update/change?
  • Are you uploading a dataset?
  • Have you documented Introduction, Architecture Diagram, Prerequisites, Usage, Sample Prompts, and Clean Up steps in your example README?
  • I agree to resolve any issues created for this example in the future.
  • I have performed a self-review of this change
  • Changes have been tested
  • Changes are documented

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

kaleko and others added 4 commits October 16, 2025 17:44
This commit introduces a comprehensive CDK alternative to the existing CloudFormation
basic-runtime sample, providing a cleaner and more maintainable Infrastructure as Code
approach for deploying Amazon Bedrock AgentCore resources.

- **Complete CDK stack** (`basic_runtime_stack.py`) with proper construct separation
- **Dedicated IAM role construct** (`infra-utils/agentcore_role.py`) for reusability
- **Custom Lambda function** (`infra-utils/build_trigger_lambda.py`) for CodeBuild automation
- **S3 asset-based source packaging** eliminating Docker dependency for users
- **ARM64 CodeBuild integration** with automated container image building
- **Comprehensive documentation** matching CloudFormation sample structure

- Uses S3 assets instead of inline code for better maintainability
- Separates infrastructure utilities into dedicated `infra-utils/` directory
- Implements proper CDK patterns with construct separation
- Provides cleaner deployment experience (~5-10 min vs ~10-15 min)

- **Basic Strands agent** (`agent-code/basic_agent.py`) with simple Q&A functionality
- **ARM64 Dockerfile** optimized for AgentCore runtime requirements
- **Proper dependency management** with isolated requirements

- Updated title to reflect both CloudFormation and CDK options
- Added comprehensive CDK section with architecture highlights
- Included CDK prerequisites with version requirements (CDK 2.218.0+)
- Updated repository structure to show new CDK directory layout
- Added installation commands for required CDK dependencies

- Complete documentation following CloudFormation sample structure
- Detailed prerequisites, deployment, testing, and cleanup instructions
- Sample queries and troubleshooting sections
- Architecture explanation and use case descriptions

- **CDK 2.218.0+** required for BedrockAgentCore construct support
- **Python 3.8+** and **constructs>=10.0.79** for proper CDK functionality
- **S3 assets** for source code packaging without size limitations

- ECR repository for container image storage
- CodeBuild project with ARM64 support for automated builds
- Lambda function for build orchestration and completion waiting
- AgentCore Runtime with proper IAM permissions and networking
- Custom resource for deployment automation

- ✅ Successfully deployed and tested in AWS environment
- ✅ Verified agent functionality with sample queries
- ✅ Confirmed clean resource cleanup with `cdk destroy`

- Added David Kaleko to CONTRIBUTORS.md

This implementation provides a modern, maintainable alternative to CloudFormation
while maintaining feature parity and following AWS CDK best practices.
…tilities

This commit fixes critical Lambda function import errors that were preventing
the CDK stack deployment from completing, and reorganizes the infrastructure
utilities for better Python module compatibility.

- **Root cause**: `cfnresponse` module is only available for inline CloudFormation
  Lambda code, not when using CDK's `Code.from_asset()` approach
- **Solution**: Embedded the standard AWS-provided cfnresponse functionality
  directly into the Lambda function to eliminate import dependencies
- **Impact**: Custom resource now properly signals CloudFormation completion/failure

- **Renamed**: `infra-utils/` → `infra_utils/` for proper Python module imports
- **Fixed**: Lambda handler path to use correct Python module notation
- **Updated**: Import statements to use underscore-based directory name

- Embedded cfnresponse class with SUCCESS/FAILED constants and send() method
- Added comprehensive comments explaining why local cfnresponse is necessary
- Maintains full compatibility with CloudFormation custom resource protocol
- Proper error handling and CloudWatch logging integration

- Updated Lambda handler path: `infra_utils.build_trigger_lambda.handler`
- Fixed import statements for renamed directory structure
- Removed conditional BedrockAgentCore imports (always available in CDK 2.218.0+)

- Moved infrastructure utilities to properly named Python package
- Added package `__init__.py` for proper module structure
- Maintained clean separation between infrastructure and agent code

- ✅ Resolves hanging CloudFormation deployments
- ✅ Custom resource now properly waits for CodeBuild completion
- ✅ Stack deployment completes successfully end-to-end
- ✅ Maintains compatibility with existing CloudFormation approach

- Verified Lambda function executes without import errors
- Confirmed CodeBuild triggering and monitoring functionality
- Validated complete stack deployment cycle

This fix ensures the CDK implementation works reliably and follows Python
packaging best practices while maintaining the same deployment behavior
as the CloudFormation equivalent.
@kaleko
Copy link
Contributor Author

kaleko commented Oct 17, 2025

FYI I ran this code through an ASH security scan and (after some small changes to the Dockerfile which were included in my latest push) there are 0 vulnerabilities of any level found.

Signed-off-by: David Kaleko <[email protected]>
@krokoko
Copy link

krokoko commented Oct 20, 2025

Copy link
Contributor

@evandrofranco evandrofranco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please review all comments + these two:

  • Can the folder name be 01-getting-started-with-strands instead of basic-runtime
  • Can the created agent name be getting_started_with_cdk instead of BasicAgentDemo_BasicAgent.

@github-actions
Copy link

Latest scan for commit: 2697101 | Updated: 2025-10-20 20:33:53 UTC

Security Scan Results

Scan Metadata

  • Project: ASH
  • Scan executed: 2025-10-20T20:33:36+00:00
  • ASH version: 3.0.0

Summary

Scanner Results

The table below shows findings by scanner, with status based on severity thresholds and dependencies:

Column Explanations:

Severity Levels (S/C/H/M/L/I):

  • Suppressed (S): Security findings that have been explicitly suppressed/ignored and don't affect the scanner's pass/fail status
  • Critical (C): The most severe security vulnerabilities requiring immediate remediation (e.g., SQL injection, remote code execution)
  • High (H): Serious security vulnerabilities that should be addressed promptly (e.g., authentication bypasses, privilege escalation)
  • Medium (M): Moderate security risks that should be addressed in normal development cycles (e.g., weak encryption, input validation issues)
  • Low (L): Minor security concerns with limited impact (e.g., information disclosure, weak recommendations)
  • Info (I): Informational findings for awareness with minimal security risk (e.g., code quality suggestions, best practice recommendations)

Other Columns:

  • Time: Duration taken by each scanner to complete its analysis
  • Action: Total number of actionable findings at or above the configured severity threshold that require attention

Scanner Results:

  • PASSED: Scanner found no security issues at or above the configured severity threshold - code is clean for this scanner
  • FAILED: Scanner found security vulnerabilities at or above the threshold that require attention and remediation
  • MISSING: Scanner could not run because required dependencies/tools are not installed or available
  • SKIPPED: Scanner was intentionally disabled or excluded from this scan
  • ERROR: Scanner encountered an execution error and could not complete successfully

Severity Thresholds (Thresh Column):

  • CRITICAL: Only Critical severity findings cause scanner to fail
  • HIGH: High and Critical severity findings cause scanner to fail
  • MEDIUM (MED): Medium, High, and Critical severity findings cause scanner to fail
  • LOW: Low, Medium, High, and Critical severity findings cause scanner to fail
  • ALL: Any finding of any severity level causes scanner to fail

Threshold Source: Values in parentheses indicate where the threshold is configured:

  • (g) = global: Set in the global_settings section of ASH configuration
  • (c) = config: Set in the individual scanner configuration section
  • (s) = scanner: Default threshold built into the scanner itself

Statistics calculation:

  • All statistics are calculated from the final aggregated SARIF report
  • Suppressed findings are counted separately and do not contribute to actionable findings
  • Scanner status is determined by comparing actionable findings to the threshold
Scanner S C H M L I Time Action Result Thresh
bandit 0 0 0 0 0 0 786ms 0 PASSED MED (g)
cdk-nag 0 0 0 0 0 0 26.5s 0 PASSED MED (g)
cfn-nag 0 0 0 0 0 0 13ms 0 PASSED MED (g)
checkov 0 0 0 0 0 0 2m 0s 0 PASSED MED (g)
detect-secrets 0 0 0 0 0 0 767ms 0 PASSED MED (g)
grype 0 0 0 0 0 0 29.9s 0 PASSED MED (g)
npm-audit 0 0 0 0 0 0 165ms 0 PASSED MED (g)
opengrep 0 0 0 0 0 0 <1ms 0 SKIPPED MED (g)
semgrep 0 0 0 0 0 0 12.2s 0 PASSED MED (g)
syft 0 0 0 0 0 0 1.7s 0 PASSED MED (g)

@kaleko
Copy link
Contributor Author

kaleko commented Oct 20, 2025

@evandrofranco I'll implement these changes shortly. One clarification:

Can the folder name be 01-getting-started-with-strands instead of basic-runtime
I called it basic-runtime because I wanted the structure of 04-infrastructure-as-code/cdk/ to exactly match 04-infrastructure-as-code/cloudformation/. Should I keep basic-runtime to maintain the symmetry?

This is also why I called the agent "BasicAgent", that is what it is called in the symmetrical CFN example

@kaleko
Copy link
Contributor Author

kaleko commented Oct 20, 2025

@evandrofranco I incorporated your changes except for the renaming of BasicAgent and the directory, per my previous comment. Let me know what you think

Copy link
Contributor

@evandrofranco evandrofranco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved.

@evandrofranco evandrofranco merged commit 301fb99 into awslabs:main Oct 20, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants